home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Memphis Amiga Group / MAG diskMAGazine (1992-04)(Memphis Amiga Group).zip / MAG diskMAGazine (1992-04)(Memphis Amiga Group).adf / bBase.doc < prev    next >
Text File  |  1992-04-08  |  24KB  |  602 lines
  1.  
  2.                                  bBaseII
  3.  
  4.                                 Version 5
  5.  
  6.  
  7.                                     by
  8.  
  9.  
  10.                               Robert Bromley
  11.  
  12.  
  13.                              November 5, 1991
  14.  
  15.  
  16.  
  17.      If you would like to make a print-out of this documentation,
  18.      I would recommend that you print out the file "bBaseII_printme.doc".
  19.      It will make a neater print job.  This file is the same, except it
  20.      has all of those messy ANSI codes removed.
  21.      
  22.  
  23.                                TABLE OF CONTENTS
  24.  
  25.  
  26.       1   INTRODUCTION     .............................................  1
  27.           1.1   What is bBaseII?     ..................................   1
  28.           1.2   Feature Summary      ..................................   1
  29.           1.3   Hardware Requirements     .............................   1
  30.           1.4   Software Requirements     .............................   1
  31.           1.5   Restrictions     ......................................   2
  32.           1.6   Copyright     .........................................   2
  33.           1.7   Starting bBaseII     ..................................   2
  34.  
  35.       2   THE REQUESTERS     ..........................................   2
  36.           2.1   The ARP File Requester     ............................   2
  37.           2.2   The String Requester     ..............................   2
  38.   
  39.       3   THE CURSOR KEYS     .........................................   3
  40.           3.1   If the String Requester is NOT Open     ...............   3
  41.           3.2   If the String Requester IS Open     ...................   3
  42.  
  43.       4   THE SCREEN GADGETS     ......................................   3
  44.  
  45.       5   THE PROGRESS BAR     ........................................   3
  46.  
  47.       6   THE MENUS     ...............................................   4
  48.           6.1   Project Menu     ......................................   4
  49.              6.1.1   Create a New Database      (F1)     ..............   4
  50.              6.1.2   Open an Existing Database  (F2)     ..............   4
  51.              6.1.3   Display Entire Database     ......................   5
  52.              6.1.4   Display Matching Records    ......................   5
  53.              6.1.5   Save the Current Database  (F3)     ..............   5
  54.              6.1.6   Save As     ......................................   5
  55.              6.1.7   About     ........................................   5
  56.              6.1.8   Quit  <Esc>     ..................................   5
  57.           6.2   Sort Menu     .........................................   6
  58.              6.2.1   Incremental Sort  (F4)     .......................   6
  59.              6.2.2   Decremental Sort  (F5)     .......................   6
  60.           6.3   Search Menu     .......................................   6
  61.              6.3.1   Select Search Criteria  (F6)     .................   6
  62.           6.4   Change Menu     .......................................   6
  63.              6.4.1   Field Titles     .................................   6
  64.           6.5   Print Menu     ........................................   6
  65.              6.5.1   Displayed Record  (F8)     .......................   6
  66.              6.5.2   All Records  (F9)     ............................   6
  67.              6.5.3   Matching Records      ............................   6
  68.           6.6   Add Menu      .........................................   7
  69.              6.6.1   A Record  (F10)     ..............................   7
  70.           6.7   Delete Menu     .......................................   7
  71.              6.7.1   Displayed Record  <Del>     ......................   7
  72.  
  73.       7   OTHER FEATURES     ..........................................   7
  74.           7.1   The "Disable Save" Option     .........................   7
  75.           7.2   The Companion Program - bBaseII50K     ................   7
  76.           7.3   The Low Memory Warning     ............................   8
  77.  
  78.       8   EXAMPLE DATABASE     ........................................   8
  79.  
  80.       9   CREDITS     .................................................   8
  81.  
  82.      10   REVISION HISTORY     ........................................   8
  83.  
  84.  
  85.  
  86.      1   INTRODUCTION
  87.  
  88.      1.1   What is bBaseII?
  89.  
  90.      bBaseII is a full-featured, intuitionized, reasonably fast and, I
  91.      think you will agree, quite an easy-to-use database program.  What it
  92.      does is store, sort, sift, and search for information, (but it won't
  93.      dial your telephone).
  94.  
  95.      Once a database has been loaded from disk, all modifications are done
  96.      in RAM:, and will NOT be permanently saved until the database is Saved
  97.      to disk.  This can be done using the Menu, the Function Keys,
  98.      or upon Quiting.
  99.  
  100.      All functions of bBase may be accessed from Menus.  Most also have
  101.      keyboard equivalents for the hard-core CLIers. It multi-tasks
  102.      extremely well, as it does not burn up CPU time while not actually
  103.      performing operations.
  104.  
  105.      bBaseII was written in HiSoft BASIC Version 1.05, and compiled using
  106.      the HiSoft BASIC Professional compiler.
  107.  
  108.      
  109.      1.2   Feature Summary
  110.  
  111.      Some of the features of bBaseII are:
  112.  
  113.      - Fully intuitionized.
  114.      - Very straightforward and easy to use.
  115.      - Uses a fast (for a BASIC program) shell-sort algorithm.
  116.      - Incremental or decremental sort, on any field.
  117.      - Search in any (or all) field(s).
  118.      - Optionally display entire database, or a filtered list, a screenful
  119.        at a time.
  120.      - Print out a record, a filtered list, or the whole database.
  121.      - Optionally disable the "Save to Disk" option to prevent accidental
  122.        alteration of the database.
  123.      - Well-behaved in a multi-tasking environment.
  124.  
  125.      
  126.      1.3   Hardware Requirements
  127.  
  128.      Database programs tend to gobble up large amounts of memory.  bBaseII
  129.      is no exception.  Since bBaseII opens on it's own screen, and reserves
  130.      memory to hold a database in RAM:, it requires about 375K of memory to
  131.      run properly with a FULL 600 record database.  This could be reduced
  132.      if the maximum number of records was reduced, but it was necessary to
  133.      hard-code in something, so that's what I picked.
  134.  
  135.      I would not recommend running bBase on a basic 512 Kb machine.
  136.  
  137.      
  138.      1.4   Software Requirements
  139.  
  140.      The "arp.library" will have to be in your libs: directory, because
  141.      bBase uses the ARP file requester - but everyone should have that
  142.      there by now, right?
  143.  
  144.  
  145.      1.5   Restrictions
  146.  
  147.      - 9 fields per record.
  148.      - bBaseII: 600 records, or a database of approximately 100K,
  149.        whichever comes first.
  150.      - bBaseII50K: (Refer to Section 7.2 - "The Companion Program"): 600
  151.        records, or a database of approximately 50K, whichever comes first.
  152.           
  153.           NOTE 
  154.           Be careful when the database size exceeds 100K (or 50K for
  155.           bBaseII50K) - it will exit ungraciously if it runs out of memory.
  156.           This is the main reason I limited the maximum number of records.
  157.           Refer to Section 7.3 - "The Low Memory Warning".
  158.  
  159.      
  160.      1.6   Copyright
  161.  
  162.      bBaseII is Copyright (1991) by Robert Bromley.
  163.      All rights are retained by the author.
  164.  
  165.      Use of this program is at your own risk and discretion.
  166.  
  167.      This program is freeware, and may be distributed free of charge.
  168.      Nominal charges for copy media only, are permitted.
  169.  
  170.      
  171.      1.7   Starting bBaseII
  172.  
  173.      From the Workbench; just click on the icon.
  174.  
  175.      From the CLI; usage is:      Run bBaseII [-s] [-fFilename]
  176.  
  177.      Including the -s switch will start bBase with Saves Disabled.
  178.  
  179.      Including the -f switch will automatically load the requested database
  180.      file.  Naturally, you need to specify the full path, but leave off the
  181.      ".bbase" extension.   IE. :
  182.  
  183.                       Run bBaseII -s -fDF0:Files/Recipes 
  184.  
  185.           
  186.           NOTE 
  187.           When using the -f switch, no spaces are allowed in
  188.           the filename path.
  189.  
  190.  
  191.  
  192.      2   THE REQUESTERS 
  193.      
  194.      2.1   The ARP File Requester
  195.  
  196.      The requester used when asking for a file to Load or Save is the
  197.      standard ARP file requester.
  198.  
  199.      
  200.      2.2   The String Requester
  201.  
  202.      This requester is used for general input.  It has full editing
  203.      capabilities.  It may be blanked at any time by pressing <Alt-X>.
  204.      Any time this requester is open, pressing <Esc> will close it.
  205.  
  206.  
  207.  
  208.      3   THE CURSOR KEYS 
  209.      
  210.      3.1   If the String Requester is NOT Open:
  211.  
  212.      Pressing the Cursor Up key will take you directly to the First Record.
  213.      The Cursor Down key displays the Last filled Record.
  214.      The Cursor Left key shows the Previous numerical Record, and
  215.      the Cursor Right key will show the Next numerical Record.  
  216.  
  217.      You can also move through the records using the mouse (Refer to
  218.      Section 4 - "THE SCREEN GADGETS").  The VERY last record is always
  219.      blank, which is where additional records may be entered.  This blank
  220.      record is accessed through the "Add" Menu item, or by pressing F10.
  221.  
  222.      
  223.      3.2   If the String Requester IS Open:
  224.  
  225.      Whenever you are in Edit Mode (ie. the string requester is open, so
  226.      that you may Enter or Change data), Cursor Left/Right moves the cursor
  227.      within the gadget, while Cursor Up/Down moves through the fields.
  228.  
  229.  
  230.  
  231.      4   THE SCREEN GADGETS 
  232.  
  233.      The Information Box at the bottom of the screen contains a      /\
  234.      gadget that looks something like that shown at the right.       ||
  235.      This gadget represents the Cursor Keys, and you can move     <== G ==>
  236.      about the database using these gadgets and the mouse            ||
  237.      instead of the Cursor Keys, if you so desire.                   \/ 
  238.  
  239.      Clicking on the Up Arrow will take you directly to the First Record.
  240.      Clicking on the Down Arrow will take you to the Last filled Record.
  241.      The Left Arrow will show the Previous numerical Record to the one
  242.      currently displayed, and the Right Arrow will show the Next Record.
  243.      If the Last Record is currently displayed, this will take you to the
  244.      blank record, where a new record may be entered, although this is more
  245.      easily accomplished by using the "Add" Menu item, or by pressing F10.
  246.  
  247.      Clicking on the "G" in the center of the arrows will bring up the
  248.      string requester, asking for the number of a record to "Goto".
  249.      After entering a legal number, the requested record will be displayed.
  250.  
  251.  
  252.  
  253.      5   The PROGRESS BAR 
  254.  
  255.      When time consuming actions are being performed, ie. Loading,
  256.      Searching, Saving, Sorting, etc., a "progress" bar will appear to
  257.      assure you that "something is happening", and visually display
  258.      to you just how the job is progressing.
  259.  
  260.  
  261.  
  262.      6   THE MENUS 
  263.  
  264.      bBase operation is best described by the operation of the Menus.
  265.      The keyboard equivalents, where applicable, are shown along with the
  266.      Menu Titles.
  267.  
  268.      
  269.      6.1   Project Menu
  270.      
  271.      6.1.1   Create a New Database  (F1) 
  272.  
  273.      This will bring up the ARP file requester, asking for a name for your
  274.      new database.  Any filename of 20 characters or less will do.
  275.      The requester will then ask how many fields the new database will
  276.      require.  bBase will accept up to 9 fields in each database.
  277.  
  278.      You are then asked for the TITLES of each field of the database.
  279.      Each field title may be a maximum of 19 characters long.  A "(1)" will
  280.      appear, along with the string requester.  Enter the title of your
  281.      first field, ie. Last Name, First Name, Company, Address, or anything
  282.      else.  When it is correct, hit <Return>, and a "(2)" will appear on
  283.      the next line with the requester.  Enter the title of the second
  284.      field.  Enter all the field titles in this manner.
  285.  
  286.      The screen will now show all the field titles, an Instruction Box, the
  287.      File Name as first entered, a blank data area, and the Record Number,
  288.      which at this point will be "1".
  289.  
  290.      The data requester will now appear in the first field of the first
  291.      record, ready for you to enter data.  Enter the data.
  292.           
  293.           NOTE 
  294.           Double quotes may not be used in any data field, as that will
  295.           mess up the alignment of all the following fields.
  296.           Single quotes are OK.
  297.  
  298.      A data entry may be a maximum of 46 characters long.  When it is
  299.      correct, hit <Return> again, and the requester will move to the second
  300.      field.  When all fields are complete, the Record Number will indicate
  301.      "2", and the data area will go blank, (because there is not yet a
  302.      Record Number 2).  Hitting <Return> again will start the process of
  303.      entering data into the second record.  Complete all records in this
  304.      manner.  In this version there is a limitation of 600 records.
  305.  
  306.      If you had been working on an existing database, and it had been
  307.      altered, you would have been asked if you wanted to Save it before
  308.      creating a new one.
  309.      
  310.      6.1.2   Open an Existing Database  (F2) 
  311.  
  312.      If you have previously created a database, and the
  313.      "Database_name.bbase" file is stored on a disk, then use this item to
  314.      access that database.  If you are working on an existing database, and
  315.      it has been altered, you will be asked if you want to Save it before
  316.      loading another.  Enter the path to the database file in the requester,
  317.      and that database will be retrieved and shown on screen.  Only files
  318.      having the extension ".bbase" will be accepted.  Use the Cursor keys
  319.      or mouse to move about the database.  Refer to Section 3 - "THE CURSOR
  320.      KEYS", and Section 4 - "THE SCREEN GADGETS".
  321.  
  322.      While a record is displayed, the Information Box will instruct you to
  323.      press "<Return> to Change Data".  Do so, and the requester will appear
  324.      in the first field, with that field's data. <Return> or Cursor Up/Down
  325.      to the field you want to change, and make the changes.  At this point,
  326.      you may either <Return> through all fields, or press F10 to exit the
  327.      Editing Mode.  The altered record will be displayed.
  328.           
  329.           NOTE 
  330.           ANY time you are in Edit Mode, whether Entering, Changing or
  331.           Searching for data, pressing F10 will exit the Edit Mode, and use
  332.           the data shown when you exited.
  333.      
  334.      6.1.3   Display Entire Database 
  335.  
  336.      If you want to quickly glance at more than one record at a time,
  337.      this will open a full-sized screen, and display the first 70 or so
  338.      characters of ALL records, one record to a line.
  339.  
  340.      The display will pause after each 23 records - click on "Next Page" or
  341.      press any key to see the next screenful, or click on "Prev Page" to
  342.      see the preceding page.  Click on "Cancel", or Press <Esc> to leave
  343.      this function.  If you see a record you want to examine in detail,
  344.      just click on it.  You will then exit the Display window, and return
  345.      to the Main Screen, with the requested record displayed.
  346.      
  347.      6.1.4   Display Matching Records 
  348.  
  349.      This works the same as the previous item, except that ONLY those
  350.      records that match the most recent Search pattern are displayed.  
  351.      (Refer to Section 6.3 - "Search Menu").
  352.      
  353.      6.1.5   Save the Current Database  (F3) 
  354.  
  355.      If the database has been altered since last saved, it will be Saved
  356.      to disk under the current filename, after confirmation.  The file
  357.      will have the extension ".bbase" automatically appended.
  358.  
  359.      If it has NOT been altered, you will be so informed, and given
  360.      the oportunity to abort the Save.
  361.      
  362.      6.1.6   Save As 
  363.  
  364.      You will be prompted for a name to Save the database.
  365.           
  366.           NOTE 
  367.           Do NOT include the ".bbase" extension at this time.
  368.           It will be appended automatically.
  369.      
  370.      6.1.7   About 
  371.  
  372.      The usual stuff.
  373.      
  374.      6.1.8   Quit  <Esc> 
  375.  
  376.      If the database has been altered, you will be asked if you want to
  377.      Save it before Quiting.
  378.  
  379.      
  380.      6.2   Sort Menu
  381.  
  382.      You may sort the records in the database based on the data in any
  383.      field.  The Sort routine is very efficient for a BASIC program.
  384.      
  385.      It will sort 200 records in less than 10 seconds on a standard A2000.
  386.      As the database size increases, naturally it tends to slow down.
  387.      
  388.      6.2.1   Incremental Sort  (F4) 
  389.  
  390.      The requester will ask which field you want to sort on.  The records
  391.      will be incrementally sorted on that field, and Record Number 1 of
  392.      the new list will be shown.
  393.      
  394.      6.2.2   Decremental Sort  (F5) 
  395.  
  396.      Same as above, but records are sorted and displayed from z-A, or 9-0.
  397.  
  398.      
  399.      6.3   Search Menu
  400.      
  401.      6.3.1   Select Search Criteria  (F6) 
  402.  
  403.      The requester will appear in the first field of a blank record.  
  404.      <Return> or Cursor Up/Down down to the field that contains the data
  405.      you want to search for.  Enter the search string in that field.
  406.      A search string may be entered in more than one field.  When all the
  407.      criteria has been entered, <Return> through all the fields, or press
  408.      F10.  All records that match ALL the search criteria will be
  409.      displayed, one by one.  When a record is found, you may Print it, 
  410.      Cancel the search, Continue searching, or Review all the records that
  411.      match that Search pattern.  (Refer to Section 6.1.4 - "Display 
  412.      Matching Records").  Search is NOT case dependent.
  413.  
  414.      
  415.      6.4   Change Menu
  416.      
  417.      6.4.1   Field Titles 
  418.  
  419.      Use this item to change the Template, ie. the Titles of your fields.
  420.      The NUMBER of fields may not be changed.  The data itself is
  421.      unaffected by this procedure.
  422.  
  423.      
  424.      6.5   Print Menu
  425.      
  426.      6.5.1   Displayed Record  (F8) 
  427.  
  428.      This item will send the displayed record to the PRT: device.
  429.      
  430.      6.5.2   All Records  (F9) 
  431.  
  432.      This item will send the entire database to the PRT: device.
  433.      
  434.      6.5.3   Matching Records 
  435.  
  436.      Sends all records that match the most recent Search pattern to the
  437.      PRT: device.
  438.  
  439.  
  440.      6.6   Add Menu
  441.      
  442.      6.6.1   A Record  (F10) 
  443.  
  444.      Positions you at the last (empty) record, with the input requester
  445.      open, ready for you to enter data into the first field.  Use the
  446.      <Esc> key to back out if you arrived here by mistake.
  447.  
  448.      
  449.      6.7   Delete Menu
  450.      
  451.      6.7.1   Displayed Record  <Del> 
  452.  
  453.      After confirmation, the record currently displayed is Deleted.
  454.  
  455.  
  456.  
  457.      7   OTHER FEATURES 
  458.      
  459.      7.1   The "Disable Save" Option
  460.  
  461.      As a simple security device, mainly as a guard against someone
  462.      accidentally altering or erasing data, I have added an option which
  463.      will disable the ability to save database changes to disk.  
  464.  
  465.      To disable Saves, simply press "Alt - S" simultaneously.  The titlebar
  466.      will briefly inform you that Saves are disabled, and now any attempt
  467.      to Save the database to disk will be circumvented.  In this case, upon
  468.      Quiting, a requester will ask if you want to Save the database
  469.      (as usual).  If you select "Save", a second requester will inform you
  470.      that the Save option has been disabled.  To Save the database, at the
  471.      next requester, "Do you Really want to Quit?", select "Cancel",
  472.      re-enable Saves, and Quit again.
  473.  
  474.      If you are running bBase from the CLI, using the "-s" flag on the
  475.      command line will start bBase with the Saves already disabled.
  476.  
  477.      The "Alt - S" combination will toggle between Save Enabled and Save
  478.      Disabled.  The titlebar message will keep you informed of the current
  479.      status as it changes.
  480.  
  481.      
  482.      7.2   The Companion Program - bBaseII50K
  483.  
  484.      I am including in this package a companion program (bBaseII50K) for
  485.      those users who are having memory problems while running bBaseII.
  486.      bBaseII50K is identical to bBaseII except that it reserves about 100K
  487.      less memory for operation, and has a database limit of about 50K.
  488.  
  489.      If anyone should need a database of more than 600 records, and have
  490.      the memory to support it, no problem - just let me know!
  491.  
  492.  
  493.      7.3   The Low Memory Warning
  494.  
  495.      When bBaseII is run, it reserves about 200K of memory, (bBaseII50K is
  496.      less) to use for database storage in RAM, arrays, etc.  No matter how
  497.      much RAM your computer has, this is all that is available to bBase!
  498.      When a database is first loaded (and only then), bBase will check
  499.      the available memory left in the program pool.  If the memory
  500.      available to bBase is less than 2K, this means that you have a
  501.      humungous database of over 100K, and only another 5-10 records may be
  502.      added before the program will crash.  In this case, you will be
  503.      advised of the situation.  Press any key to cancel the warning.
  504.      The recommended action is: 
  505.  
  506.         1.  If you are using bBaseII50K, start using bBaseII.
  507.         2.  If you are using bBaseII, delete some old records.
  508.         3.  Give me a call.  We can get you a larger version.
  509.         4.  Upgrade from bBase to dBase.
  510.           
  511.           NOTE 
  512.           If you are loading a new database after having just finished
  513.           work on another, it is possible get get a false warning here.
  514.           If you know your database size is within limits,
  515.           I think you can safely disregard this warning.
  516.  
  517.  
  518.  
  519.      8   EXAMPLE DATABASE 
  520.  
  521.      There is an example database included in this package.  Everyone uses
  522.      the Name and Address example, so I opted for something different.
  523.      The file "Recipes.bbase" is a sample database showing one way of
  524.      keeping track of recipes, without having to re-type them all.
  525.      It merely shows where they can be found when needed.  With this
  526.      database you can Sort the recipes by Name, Catagory, or anything else.
  527.      You can Search for all recipes containing a listed ingredient, recipes
  528.      you have already served to given people, or just the location of the
  529.      recipe if you have forgotten which of your 647 recipe books it is in.
  530.      I have found this to be very useful.
  531.  
  532.  
  533.  
  534.      9   CREDITS 
  535.  
  536.      My thanks to Peter Keegan, of Harvard, Massachusetts, and to Bobby
  537.      Foreman, of West Sacramento, California, for taking the time to write
  538.      in and point out some of the deficiencies of Version 1.
  539.  
  540.  
  541.  
  542.      10   REVISION HISTORY 
  543.  
  544.      Version 1:     First release - May 1991
  545.  
  546.      Version 2:     Internal
  547.  
  548.           - Added F10 shortcut to quit editing.
  549.           - Added <Esc> to return directly to program.
  550.           - May now cursor up/down through fields while editing.
  551.           - Added the ability to specify a database on the command line.
  552.           - Added <Esc> to Quit via keyboard.
  553.           - Added the "Add a Record" menu item.
  554.           - Bug fixes.
  555.  
  556.      Version 3:     Internal,  September 1991
  557.  
  558.           - Added the "Display Entire Database" and "Display Matching
  559.             Records" menu items.
  560.           - Add "Print Matching Records" menu item.
  561.           - Changing the maximum number of records was causing crashes.
  562.             Hard-coded maximum at 600 records, and alloted memory
  563.             accordingly.
  564.           - Added the -s and -f command line options.
  565.           - Changed colors to make the screen more readable.
  566.           - Added the Progress Bar.
  567.           - Changed the sort algorithm from Bubble to Shell.  Much faster.
  568.           - More bug fixes.
  569.  
  570.      Version 4:     Internal,  October 1991
  571.  
  572.           - Can now go directly to a record from the "Display Entire
  573.             Database" and "Display Matching Records" windows, by clicking
  574.             on it.
  575.           - Field Titles now stay neater after being changed.
  576.  
  577.      Version 5:     Released November 1991
  578.  
  579.           - The Sort algorithm is now case independent.
  580.           - Added the Low Memory Warning.
  581.           - Bad bug: If the database was sorted decrementally, on a field
  582.             which was blank in some records, and a record was deleted,
  583.             one record's data would become corrupted.  Now fixed.
  584.           - When Displaying Entire Database, or Matching Records, you can
  585.             now back up, and display the Previous Page.
  586.           - Still more bug fixes.
  587.  
  588.  
  589.  
  590.      It's taking me a long time to find all these bugs by myself, and I
  591.      know it's still not perfect.  If anyone out there is using this
  592.      thing, I would appreciate some constructive criticism.
  593.  
  594.      Name and address in "About".
  595.  
  596.      Email (until April 1992): CRS; Conference 5, 
  597.      or Usenet; Bob.Bromley@canrem.uucp
  598.  
  599.      Hope someone finds this useful.
  600.  
  601.      Bob
  602.